The Rules dealing with XML entries (container)

Rule Name:

Replace any tabs in XML with 3 spaces

Position:

Under: The Rules dealing with XML entries

Name:

XML_RemoveTabs

Default:

Checked

Usage:

The XML schema is parsed and any occurrences of tab characters are replaced with spaces. 

Spaces are preferred over tabs so that when printed in a mono-spaced type the listing appears correct. If changes were made, a note is added to the log and displayed. 

Rule Name:

Replace any non-ASCII chars (values >127) with pure ASCII

Position:

Under: The Rules dealing with XML entries

Name:

XML_JustASCII

Default:

Checked

Usage:

The XML schema is parsed and any occurrences of characters with hex values above 127 (which are in fact illegal in ITS-style XML which uses the UTF-8 encoding) are replaced.

The replacement strings are taken from similar characters when possible (for example, the right hanging quote symbol is replaced with a straight quote)  If changes were made, a note is added to the log and displayed. 

Rule Name:

Warn when a message record does not produce an element entry

Position:

Under: The Rules dealing with XML entries

Name:

XML_msg

Default:

Checked

Usage:

If the record type is of type “message” then normally an <element> entry is also created when the XML is created. For all other types (as well as for the message), an abstract type is created (there is no element).  A type is a better choice for reasons of data reuse.  

Side note: If you pick up your typical “idiot’s guide to XML” textbook you will see extensive use of elements being created in the examples, rather than types.  This is reflective of the author’s lack of understanding data reuse concepts, and the ITS style does not follow it.

Rule Name:

Warn when an XML name does not match the ASN name

Position:

Under: The Rules dealing with XML entries

Name:

XML_name

Default:

Checked

Usage:

The typical pattern followed by standards creators is to have the ASN and XML proper  names match.  The tool, when it automatically creates the XML listing by translating the ASN listing, follows this naming convention.  The user may change the names to something different, and if this is the case the tool will maintain that name (even as it updates the XML listing).  This rule provides a warning when such different names are found in the record.  This may not be an error, but as general style guideline, it should be avoided. 

Warning:  If you create records with different XML names than ASN names, then you should be very careful always to leave the option “Skip Link Resolution Testing” UN-checked when creating XML.   This setting ensures that the tool will convert each fragment of ASN used in another record to its XML form, then seek out the correct record for the entry and use the actual (perhaps different) XML name for the element.  Various warnings are produced if no matching record is found, if no XML is found, or if multiple records are found.  See the page on converting to XML here for further details of this process.  Keep in mind that should you change the ASN name of the entry the XML name may also need to be changed.

Rule Name:

Automatically set message records to produce elements (restore defaults)

Position:

Under: The Rules dealing with XML entries

Name:

XML_AutoMsg

Default:

UN-Checked

Usage:

The typical pattern followed by standards creators is to produce XML “types” for all record entries except for messages, where a type and an element are produced.  This rule, when enabled, restores the checkbox “Make an Element Entry” to its default state (checked for message record types, unchecked for others). 

See also the rule Warn when a message record does not produce an element entry above this page.

Rule Name:

Automatically set to auto-update XML (will lose any manual editing)

Position:

Under: The Rules dealing with XML entries

Name:

XML_AutoUpdate

Default:

UN-Checked

Usage:

The typical usage pattern followed by standards creators is to allow the tool to re-create the XML automatically when needed and there is almost no occasion to actually edit it by hand.  Should such editing occur in a record, the Allow Updating of XML… checkbox becomes UN-checked and further automatic updating of the record is disabled.  Thus, the user’s manually added editing is preserved. 

If the user subsequently presses Create XML then an automatically generated set of XML is again created and the check box is again checked.   This rule is used to reset the record (or all records in a table) to enable auto-updates to occur again.